写你的第一个DeepSeek Harness插件：10分钟从零到加载成功-AI助手

写你的第一个DeepSeek Harness插件：10分钟从零到加载成功

2026-08-18 17:33:17 41 AI智能编辑DB DeepSeek Harness 插件开发 Cordis TypeScript Agent工具

先说结果

Harness 插件基于 Cordis 插件系统，最小插件只需要4个元素：name、inject、apply、工具注册。本文手把手带你写一个 greet 工具插件，从源码环境到 Agent 调用成功，全程10分钟。附完整可复制代码。

一、Harness 插件系统原理

DeepSeek Harness 的核心理念是"一切皆插件"，这个理念不是营销词，是字面意思。模型、工具、Skill、会话、沙箱、存储、Agent 循环、甚至 Web UI，全部都是插件。

插件系统基于 Cordis——一个 TypeScript 插件框架。每个插件声明自己依赖哪些服务（inject），在 apply 函数里注册新能力，卸载时由框架统一清理。这种设计让你可以替换任何一个组件，而不用改 Harness 源码。

一个最小插件的生命周期只有三步：加载 → 注册能力 → 被调用。理解了这个，写插件就很简单了。

二、写第一个 greet 插件（5步）

准备源码环境。开发 TypeScript 插件需要进入 Harness 源码仓库，不能只用 npx。执行 git clone、corepack enable、pnpm install、pnpm run build。注意 Node.js 版本要求 ^22.19.0 || >=24.0.0，建议直接用 Node 24。pnpm run build 不能省，否则 Web 页面缺少构建产物。

创建插件文件。在仓库根目录建 scratch-plugin/src/，新建 greet-tool.ts。插件只有四个部分：name（插件名）、inject（声明依赖 tools 服务）、apply(ctx)（加载入口）、ctx.tools.register()（注册工具）。parameters 告诉模型传什么参数，execute 真正执行代码，output 约定结果格式。

写 cordis.yml 配置。新建 scratch-plugin/cordis.yml，用 insert 把插件挂进配置树。name 字段必须填插件文件的绝对路径（用 pwd 确认）。插件最好放在 Harness 源码仓库内，否则可能出现 Cannot find module 错误。

启动并检查。执行 pnpm dsh web --patch ./scratch-plugin/cordis.yml。看到 [greet-tool] loaded 和 dsh web: http://127.0.0.1:3080 两行就说明成功了。进入"设置→插件→插件列表"，搜索 greet-tool，状态应为"已启用"。

让 Agent 调用它。选择工作区，新建标准模式会话，输入"请调用 greet 工具问候 Datawhale"。展开工具调用，可以看到输入 {"name":"Datawhale"} 和输出"你好，Datawhale！你的第一个 Harness 插件已经运行。"至此最小闭环跑通。

三、附：完整可复制代码

greet-tool.ts 完整代码，直接复制：

import type { Context } from '@deepseek-ai/cordis'

import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'

export const inject = ['tools']

export function apply(ctx: Context) {

ctx.tools.register(defineTool({

description: 'Greet someone by name.',

parameters: {

type: 'string',

required: true,

description: 'The name to greet',

output: {

schema: { type: 'string' },

render: (_args, value) => [{ type: 'text', text: value }],

async execute(args) {

return `你好，${args.name}！你的第一个 Harness 插件已经运行。`

}))

console.log('[greet-tool] loaded; tool name: greet')

}

cordis.yml 配置和启动命令：

# scratch-plugin/cordis.yml（把路径换成你自己的绝对路径）

- insert:

- id: greet-tool

# 启动（带补丁）

pnpm dsh web --patch ./scratch-plugin/cordis.yml

# 端口被占用时换端口

pnpm dsh web --patch ./scratch-plugin/cordis.yml --port 3082

四、安装第三方插件

自己写插件适合学习和定制，但日常使用更推荐直接装社区插件。截至8月中旬，Oh-My-DSH 目录已收录 1100+ 个插件，覆盖视觉识别、OCR、文件处理、代码审查等场景。

安装插件：dsh plugin --profile web add @dsh-external/dsh-vision-toolkit。安装后重启 Web 服务（插件在启动时加载，只刷新页面不够）。

配置凭据：很多插件需要 API Key，用 dsh credentials set KEY_NAME 写入凭据系统，然后在设置页面配置对应引用。

加载 Skill 并调用：插件通常附带 Skill，在会话中用 /skill-name 加载，然后直接描述任务，Agent 会按需调用插件暴露的工具。

五、避坑提醒

避坑提醒

坑一：pnpm run build 不能省。只装依赖不构建，插件日志会出现但 Web 页面缺少产物，工具调用会失败。
坑二：插件路径必须是绝对路径。cordis.yml 里的 name 字段填相对路径会加载失败，用 pwd 确认绝对路径。
坑三：插件放在源码仓库外可能找不到模块。greet 插件依赖 @deepseek-ai/cordis 和 @deepseek-ai/dsh-tools，放在仓库外会出现 Cannot find module。
坑四：安装第三方插件要检查权限。插件运行在宿主进程里，属于可信代码。安装前看清楚许可证、维护者、需要的目录和网络权限。
坑五：改完插件要重启。宿主代码和浏览器代码都在启动时加载，热更新不生效，改完必须重启 Web 服务。

写插件的最小闭环是：apply(ctx) → 注册工具 → execute(args) → 返回结构化结果。理解了这四步，你就能把任何脚本、工具、API 封装成 Harness 插件。从 greet 开始，下一步可以试试封装一个文件搜索工具、一个翻译 API、或者一个你自己的业务脚本。生态刚起步，早写的插件就是早期红利。

作者声明：本作品含 AI 生成内容